Apex Classes

iDigi

This is the main class for interacting with iDigi web services. It's used as a virtual class for the DeviceCore and Dia classes.

Constructors

iDigi( iDigi_Account__c account)

Instantiates the class and uses the provided iDigi Account for all communications with the iDigi server.

Static Methods

String authBasic( String username, String password)

Returns the Base64-encoded version of 'username:password' for use in Basic Authorization of an HTTP connection.

String getChildText( Dom.XMLNode node, String element)

Helper function to get the text of a child element of an XML Node. Returns an empty string if:

the node passed in is Null
there isn't a child with the requested name

Boolean stringEqual( String a, String b)

Custom string comparison that treats Null as an empty string. In Apex, the comparison [Null == ''] evaluates as False. Calling iDigi.stringEqual( Null, '') returns True.

DateTime convertTimestamp( String iDigi_ts)

Convert an ISO 8601 timestamp (as used in iDigi) to an Apex DateTime value. Uses the JSONParser getDateTimeValue() method.

See http://en.wikipedia.org/wiki/ISO_8601 for timestamp format details.

Throws a System.JSONException if iso8601_ts is not a valid ISO 8601 timestamp.

String convertTimestamp( DateTime ts)

Convert an Apex \c DateTime value to an ISO 8601 timestamp, using the format used by iDigi ('2012-07-31T14:23:51.000Z').

iDigi_Account__c lookupAccount( String user, String server)

Helper method that ensures all necessary fields are included in the SOQL query to look up an iDigi_Account__c using a username and server.

Returns Null if user or server are Null, or there isn't a matching record.

Throws an iDigi.QueryException() if there are duplicate iDigi_Account__c records matching the request. This should never happen since a trigger ensures uniqueness.

iDigi_Device__c lookupDevice( iDigi_Account__c account, String ConnectwareId)

Helper method that ensures all necessary fields are included in theSOQL query to look up an iDigi_Device__c for the supplied iDigi_Account__c and matching the requested ConnectwareId (e.g., '00000000-00000000-00409DFF-FF012345').

Returns Null if account or ConnectwareId are Null, or there isn't a matching record.

Throws an iDigi.QueryException() if there are duplicate iDigi_Device__c records matching the request. This should never happen since the device list is managed by the DeviceCore class, which doesn't allow for duplicate entries.

Instance Properties

HttpResponse testHttpResponse

HttpRequest testHttpRequest

Unit Testing doesn't allow for HTTP Callouts, so this class provides two instance properties to use during testing. Instead of calling Http.send() when Test.isRunningTest() is True, the class copies the HttpRequest to testHttpRequest and returns testHttpResponse.

This allows for thorough testing of the class, since it's possible to examine the request that would have been sent, and to test how the class handles various responses from the iDigi server.

Instance Methods

HttpResponse testableHttpSend (HttpRequest req)

Used inside the class to wrap Http.send() and behave differently during automated tests.

HttpRequest buildRequest( String method, String url)

Create an HttpRequest object using the hostname and credentials of the iDigi_Account__c associated with this instance. Typically sent with the sendRequest() method.

Dom.Document sendRequest( HttpRequest req)

Sends an HttpRequest to an iDigi server. Generates an iDigi.RequestFailedException() if the server's response code isn't in the range of 200-299 (success).

See the buildRequest() method for generating HTTP requests.

Returns the body of the HttpResponse.

GET( String url)

Generate and send an HTTP GET request for the specified URL, using the hostname and credentials of the iDigi_Account__c associated with this instance.

POST( String url, String xmldata)

POST( String url, Dom.Document xmldata)

Generate, and send, an HTTP POST request for the specified URL with xmldata as the body, using the hostname and credentials of the iDigi_Account__c associated with this instance.

Dom.Document checkStatus()

Connect to CheckStatus web service and return the XML response.

Does not require a valid username/password for the server, just a valid hostname. Used to confirm that there is an iDigi server running on the provided hostname.

Returns the server response or Null if the server didn't provide a valid CheckStatus response

Possible exceptions:

System.CalloutException: Host isn't listed in Remote Sites for organization.

Custom Exceptions

RequestFailedException

Thrown when an HttpRequest to an iDigi server has an unsuccessful response (HTTP status is not 200-299).

QueryException

Thrown from lookupAccount and lookupDevice if they find duplicate records (which should be impossible).

DeviceCore

This is the main class for interacting with the iDigi "DeviceCore" web service. It extends the iDigi class.

Constructors

DeviceCore( iDigi_Account__c account)

Identical to the iDigi constructor.

Static Methods

iDigi_Device__c xmlToDevice( Dom.XMLNode node)

Convert a single DeviceCore XML node from a DeviceCore response into an iDigi_Device__c object. Returns Null if node is not an XML Node named 'DeviceCore'.

iDigi_Device__c[] xmlToDeviceList( Dom.Document devcoreResponse)

Convert a DeviceCore response from iDigi server to a list of iDigi_Device__c objects.

Instance Methods

Dom.Document GET()

Identical to iDigi.GET(), but uses '/ws/DeviceCore' as the URL instead of taking it as a parameter.

Integer refreshDeviceList()

Refresh the list of iDigi Device objects associated with a given iDigi Account object. Adds new iDigi Device objects that aren't already present in the data store, and sets the Inactive field to true for devices that are no longer listed in the iDigi server response.

Returns the number of devices added or updated.

Dia

This is the main class for interacting with the iDigi "DiaChannelDataFull" and "DiaChannelDataHistoryFull" web services. It extends the iDigi class.

Constructors

Dia( iDigi_Account__c account, iDigi_Device__c device)

Constructor with separate iDigi Account and iDigi Device objects. The account parameter must be the parent of the device parameter.

iDigi_Account__c must have the following fields populated: Id, username__c, password__c, server__c.

iDigi_Device__c must have the following fields populated: Id, Name, iDigi_Account__c.

Dia( iDigi_Account__c account, String device)

Constructor with separate iDigi Account and an iDigi Device ConnectwareId string. The constructor uses SOQL to look up the iDigi Device.

iDigi_Account__c must have the following fields populated: Id, Username__c, Password__c, Server__c

Dia( iDigi_Device__c device)

Constructor with a single iDigi Device object with the iDigi_Account__r field populated with the following fields: Id, Username__c, Password__c, Server__c.

In addition, the iDigi_Device__c must have the following fields populated: Id, Name, iDigi_Account__c.

Classes

Parsed_Channel

Class used to hold data parsed from "DiaChannelDataFull" or "DiaChannelDataHistoryFull" XML.

Static Methods

iDigi_Device__c getDevice( Id device_id)

Return an iDigi_Device__c with its iDigi_Account__r populated. Can be used with the Dia( iDigi_Device__c device) constructor.

Dia.Parsed_Channel xmlToChannel( Dom.XMLNode node)

Parses a single DiaChannelDataFull or DiaChannelDataHistoryFull XML Node and returns a Parsed_Channel datatype with Strings for device (id.devConnectwareId), instance (id.ddInstanceName), channel (id.dcChannelName) and units (dcUnits).

Returns Null if the XML Node is not an XML Node of the correct type.

The related xmlToReading() parses the same XML Node and returns a Dia_Reading__c object.

Dia_Reading__c xmlToReading( Dom.XMLNode node)

Parses a single DiaChannelDataFull or DiaChannelDataHistoryFull XML Node and returns a Dia_Reading__c object.

Returns Null if the XML Node is not an XML Node of the correct type.

The related xmlToChannel() parses the same XML Node and returns a Parsed_Channel object.

Instance Properties

iDigi_Device__c device

The device associated with the current instance (read-only). Note that callers can reference the Dia_Refresh__c and Dia_Status__c fields of the device after calling the loadChannelData() method to determine the result of the load.

Instance Methods

void setDevice( iDigi_Device__c device)

Method to associate an iDigi Device with a Dia instance. The iDigi_Device__c object must have the following fields populated: Id, Name, iDigi_Account__c.

Decimal getMaxHistoricId()

Return the highest HistoricID recorded for Dia samples from this instance's device.

Dom.Document channelDataHistoryFull()

Send a web services request for new Dia Readings (where dcdhId is greater than the maximum dcdhId recorded) for this instance's device.

Dia_Channel__c findOrAddChannel( Dia.Parsed_Channel lookup)

Searches the Dia Instances and Channels of this instance's device for the channel described in the "lookup" parameter. If a matching channel doesn't exist, this function creates it and inserts it into the data store.

Returns a matching Dia_Channel__c or Null if the "lookup" parameter's Connectware ID doesn't match the one for this instance.

Integer loadChannelData()

Check for new Dia readings for the given device. Returns number of records left unread.

RCI

This class extends the SCI class (since RCI requests are a subset of SCI requests) with methods focused on web services related to RCI (Remote Command Interface).

Constructors

RCI( iDigi_Account__c account)

Identical to the SCI constructor, but adds an "rci_request" child element to the sciCommand XmlNode.

Instance Properties

Dom.XmlNode rciRequest

The rci_request XmlNode of the SCI request XML document.

SCI

This class extends the iDigi class with methods focused on web services related to SCI (Server Command Interface).

Constructors

SCI( iDigi_Account__c account, String op)

Identical to the iDigi constructor, but creates a private Dom.Document instance property containing an SCI request. User code can call the SCI class methods to add to the request before sending it with the sendRequest() method.

Instance Properties

Dom.XmlNode sciCommand

The command (e.g., send_message) XmlNode of the SCI request XML document.

Instance Methods

Dom.Document sendRequest()

Send the instance's SCI request and return the body of the iDigi server's XML response.

void targetDevice( String device)

void targetDevice( List<String> devices)

Add one or more target devices to the SCI request, passed in as a single Connectware ID or a list of Connectware IDs. Each device is added to the "targets" XmlNode of the request as a "device" element with its "id" attribute set to the Connectware ID.

Back | Next